\chapter{Using HP LIMS}

In this chapter we walk through the process of setting up an instance of HP LIMS on a web server and how the application is used. We look at how to configure HP LIMS to connect to a database, all necessary changes to perform before building the application to ensure a higher level of security, and how to build HP LIMS using Maven in Section~\ref{sec:setup}. The usage of HP LIMS and the different components of the application's user interface are presented and explained in Sections~\ref{sec:mainLayout} through~\ref{sec:settings}.

\section{Setting up HP LIMS}
\label{sec:setup}

HP LIMS runs on a Java application server as a Java Servlet within a Servlet container. The following prerequisites have to be met in order to run HP LIMS:

\begin{itemize}
 \item \textit{Java}: Java version 1.5 or above is required. J2SE1.6 is recommended.
 \item \textit{MySQL}: A MySQL database is needed for persistence of data. Version 5.5.x is recommended.
 \item \textit{Web server}: HP LIMS should run on any web server implementing the Java Servlet 2.5 specification. Apache Tomcat 6 or above, or Jetty are recommended.
\end{itemize}

\subsection{Configuration}

Before building and deploying HP LIMS a few minor configuration steps have to be performed. One has to configure the application's persistence unit in order to connect to a database, and for security reasons one should also review and customize the security settings of the authentication module.

\subsubsection{Database}

Configuration of the database is done in the application's persistence module, the \texttt{persistence.xml} file mentioned in Chapter~\ref{sec:data-persistence}. Unmodified versions of HP LIMS should only need to set up the following in order to connect to a MySQL database: 

\begin{itemize}
	\item \texttt{javax.persistence.jdbc.url}: URL to the database.
	\item \texttt{javax.persistence.jdbc.user}: Database username.
	\item \texttt{javax.persistence.jdbc.password}: Database password.
\end{itemize}

\subsubsection{User authentication}

Configuration of the authentication module of the Vaadin Appfoundation addon is done in the application's context listener, \texttt{MyContextListener.java}. Parameters that can be changed in order to customize the configuration of the authentication module include the following:

\begin{itemize}
	\item \textit{Password salt value}:\index{Password salt} All passwords are combined with a salt value, as mentioned in Section~\ref{sec:authentication}. One should specify a salt value that is unique to one's application. Once set, the salt value can not be changed, as this would render already hashed passwords invalid. Care should be taken to not make the salt value available externally.
	\item \textit{Password requirements}: The default password requirements are listed below. These settings can be changed as deemed appropriate in the application's context listener:
	\begin{itemize}
		\item \textit{Minimum length}: Passwords should be at least six characters long.
		\item \textit{Lowercase required (a-z)}: No. 
		\item \textit{Uppercase required (A-Z)}: No.
		\item \textit{Numbers required (0-9)}: No.
		\item \textit{Special characters required}: No.
	\end{itemize}
	\item \textit{Maximum failed login attempts}: To protect against brute-force attacks, Appfoundation allows for locking user accounts after a given number of unsuccessful login attempts. By default, five unsuccessful login attempts will get a user's account suspended. If it is desired to change this value, the \texttt{authentication.maxFailedLoginAttempts} parameter can be used.
\end{itemize}

\noindent When the application has been set up to connect to a database and the authentication module has been configured properly to satisfy one's requirements it is time to build the application and deploy it to a web server.

\subsection{Build and deploy to server}

HP LIMS is a Maven project, so it can be built with the following Maven command:\\

\texttt{mvn install}\\

Building HP LIMS with Maven will create a WAR package that can easily be deployed to a Java web server. One can also deploy HP LIMS to a Jetty server instance by using the following Maven command:\\

\texttt{mvn install jetty:run}\\

HP LIMS can be run in \textit{debug mode} or \textit{production mode}. Debug mode is enabled by default, and production mode can be enabled by setting the \texttt{productionMode} parameter in the \texttt{web.xml} file to true. More about debug and production mode in Vaadin applications can be found in \cite{bookOfVaadin}.

\section{HP LIMS main layout}
\label{sec:mainLayout}

After a user has been authenticated through the login view the user gains access to the main layout of HP LIMS. A welcome screen, shown in Figure~\ref{fig:welcomeScreen}, is displayed to the user. 

\begin{figure}[htb]
\centering
\includegraphics[scale=0.55]{figures/welcomeScreen.eps}
\caption{HP LIMS main layout.}
\label{fig:welcomeScreen}
\end{figure}

HP LIMS' main layout consists of some fixed components that are viewable throughout the application's user interface. A button for logging out of the application is placed at the top right corner along with a search field, conforming to accepted web design principles laid out by \citeauthor{webUsability} \cite{webUsability}. 

A tab based navigation system has been chosen for HP LIMS. Tabs for the home screen, and a general view of orders, experiments, settings and help are permanent, while individual orders, experiments and search results are displayed in their own closable tabs.

\section{Orders}

Orders are probably the most important part of HP LIMS. It is through the \textit{Orders} tab that all the heavy peptide orders are tracked and administered. Figure~\ref{fig:ordersTab} shows HP LIMS' order tab. The order tab displays a list of all orders currently stored in the database. Each order is initially given a name based on its unique ID in the database, but this name can be changed later to accomodate much simpler identification of each order.

\begin{figure}[htb]
\centering
\includegraphics[scale=0.5]{figures/ordersTab.eps}
\caption{HP LIMS \textit{Orders} tab provides a general overview of all the orders currently stored in the database.}
\label{fig:ordersTab}
\end{figure}

Figure~\ref{fig:ordersTab} shows that there are currently two orders in the database. Each order has been given a unique ID, shown in the Order ID column. The two orders have been created by two different users, and contain 24 and 38 peptides respectively.

An individual order can be accessed by double-clicking on it in the list of orders. A double-click will open a new tab displaying the selected order. A new order can be created by pressing the \textit{New Order} button in the top left corner of the view, in which case a new tab with the newly created, empty, order is opened.

\subsection{Individual orders}

An individual order displays a list of the peptides that are currently associated with this order. As mentioned above, each order is displayed in its own tab, a design choice that was made to be able to easily compare different orders. An earlier version of HP LIMS displayed the orders within the \textit{Orders} tab, a design that did not allow for displaying more than one order at the time.

\begin{figure}[htb]
\centering
\includegraphics[scale=0.5]{figures/individualOrder.eps}
\caption{HP LIMS displays individual orders in separate, closable tabs.}
\label{fig:individualOrder}
\end{figure}

Figure~\ref{fig:individualOrder} shows an example of how an order is displayed to the user in HP LIMS. On the top we have created a toolbar where buttons with the following functions have been placed:

\begin{itemize}
	\item \textit{Add}: More peptides can be added to the order by pressing this button. It will bring up a window with an interface for adding peptides. More details on this follows in Section~\ref{subsec:addingPeptides}.
	\item \textit{Import}: When the peptides in this order have been received at PROBE, one can add information about these peptides by importing the data pertaining to the peptides from an Excel spreadsheet. Clicking the \textit{Import} button will display an upload component where the user can upload a file to the server to start the import procedure, as discussed in Section~\ref{sec:uploadFile}. After the import of data has finished, the order is considered \textit{completed}, and thus peptides can no longer be added to this order.
	\item \textit{Export}: When submitting an order, each company requires the order to be on their own unique standard format, as mentioned in Chapter~\ref{chap:existingSystem}. We have not implemented an automatic export tool that will generate orders on each of these different formats. Instead, the information needed for filling out an order is exported as a tab separated text file. For each peptide, its UniProt accession number, name, and sequence are exported.
	\item \textit{Labels}:  When the Labels button is pressed HP LIMS generates a PDF file with labels for each peptide tube. As can be seen from Figure~\ref{fig:individualOrder}, this button is disabled by default. After an order has been completed (by using the Import button), enough information has been gathered in order to print labels and stick them on the tubes containing the peptides.
\end{itemize}

Every order is given a name that can be changed by using the \textit{Edit} link next to the order's name. In every order a list of all peptides associated with the order is displayed. Orders that have not been completed display the following information about the peptides:

\begin{itemize}
	\item \textit{Accession \#}: Each peptide belongs to a protein. The UniProt accession number of this protein is presented as a link. Clicking on the link will open the protein's UniProt page, revealing more information about said protein.
	\item \textit{Peptide name}: Peptides are given names, generated from the protein it belongs to, and where in the protein it is located.
	\item \textit{BLAST hits}: Number of hits returned from a BLAST search on the peptide's sequence. Most peptides will only have one hit, but it is important to inform the user if there were more or less than one BLAST hit for a particular peptide. In such cases, the peptide becomes subject to manual review.
	\item \textit{Sequence}: The peptide's sequence is displayed to let users separate between different peptides and identify which amino acids a particular peptide consists of. Any known modifications on specific amino acids or stretches of amino acids in a sequence are highlighted in red.
	\item \textit{Length}: Peptide sequence length.
\end{itemize}

Users can select which modifications to highlight using the \textit{Modifications} button. There are quite a few different types of modifications, but for the use of HP LIMS only three types of modifications are interesting: modified residues, variants and sites.

Orders that have been completed display more information than incomplete orders. When completed, orders will also display, amongst others, the plate position, the amount, and the molecular weight of the peptide.

\subsection{Adding peptides to an order}
\label{subsec:addingPeptides}

Peptides are added to orders through the \textit{Add Sequences} window shown in Figure~\ref{fig:addWindow}. A user can bring up this window by pressing the \textit{Add} button in an order, shown in Figure~\ref{fig:individualOrder}. The window is set to be modal, and is automatically brought up when creating a new order or when opening previously created, empty orders. A modal window is a window that is given all the focus within an application, and usually requires the user to interact with it before continuing operations in the rest of the application. Modality has been set on this window to give it focus, but the user is not required to add any peptides right away, though this is usually desired.

\begin{figure}[htb]
\centering
\includegraphics[scale=0.6]{figures/addWindow.eps}
\caption{Adding peptides to an order is done with the \textit{Add Sequences} window.}
\label{fig:addWindow}
\end{figure}

Peptide sequences can be added to an order by typing (or pasting) a list of sequences into the text field. It is possible not only to add peptide sequences, but also entire protein sequences. Protein sequences can be added in FASTA format or as a pure protein sequence without any header information. To do this one selects \textit{Protein sequences} as input type instead of the default input type; peptide sequences. It is also possible to select \textit{UniProt accession number} as input type if one does not have the entire protein sequence available, the protein sequence will then be fetched from the UniProt database. Each entry, both for peptide sequences, protein sequences and UniProt accession numbers, is separated by a line break. When the input type is either protein sequences or UniProt accession numbers, \textit{in silico} digestion of the sequences are performed. An enzyme (protease) to use in the \textit{in silico} digestion has to be selected from the drop-down menu \textit{Enzyme}. Trypsin is the most commonly used enzyme for digestion, as mentioned in Chapter~\ref{proteinBackground}, and is thus set as the default enzyme in the drop-down menu.

Peptides are validated and submitted for BLAST search when the \textit{Submit} button is clicked. Sequences are validated, and warnings are displayed for any sequences not conforming to the currently active rule set. BLAST search is automatically started for valid peptides, and if a warning is displayed for a sequence, the sequence can either be deleted with a single click, or it can be edited without having to look it up in the input field. 

\subsubsection{Rule management}

Rules can be managed when adding peptides to an order. From the \textit{Add Sequences} window a new, modal, window can be opened - the \textit{Select Sequence Validation Rules} window. This windows consists of two different components, as shown in Figure~\ref{fig:ruleWindow}. Each component is responsible for a task related to rule management.

\begin{itemize}
	\item  The first component, \textit{Select Rules}, is responsible for handling activation and deactivation of rules, presented as two lists of rules. The left column lists all the inactive rules (rules that will be ignored), and the right column lists all the currently active rules. One can select rules from one column and move them to the other column either by clicking on the \textit{$\ll$} or \textit{$\gg$} buttons, or by pressing Enter, thereby deactivating or activating the selected rule(s).

\item The second component of the \textit{Select Sequence Validation Rules} window, \textit{Create New Rule}, is a form that is used for creating new rules, and consists of five different groups of rule properties, in addition to a text field for giving the rule a descriptive name. Rules can be of three different types: length, allow, and disallow. How the different rule types and their properties work was described in Section~\ref{sec:ruleManagement}, and does not need further elaboration here. Properties belonging to a group that is not needed for specifying a given rule type is disabled to avoid confusion when creating new rules.
\end{itemize}

\begin{figure}[htb]
\centering
\includegraphics[scale=0.6]{figures/ruleWindow.eps}
\caption{\textit{Select Sequence Validation Rules} window.}
\label{fig:ruleWindow}
\end{figure}

\section{Experiments}

Experiments are another important part of HP LIMS. Although not as critical as orders, experiments have proven to be quite a useful tool in HP LIMS. As mentioned in Section~\ref{sec:experiment}, an experiment is a collection of peptides, but unlike orders, a peptide can be part of several experiments. The \textit{Experiments} tab is laid out in the same way as the \textit{Orders} tab, with a button in the top left corner of the view to create a new experiment, and a list of experiments below. Experiments are created and opened in the same fashion as with orders, in a separate tab, shown in Figure~\ref{fig:experimentTab}.

\begin{figure}[htb]
\centering
\includegraphics[width=\textwidth]{figures/experimentTab.eps}
\caption{Individual experiments are opened in a separate tab, in the same way orders are opened. Peptides belonging to different orders can be grouped together in one or several different experiments.}
\label{fig:experimentTab}
\end{figure}

\begin{wrapfigure}{R}{0.5\textwidth}
  \begin{center}
    \includegraphics[scale=0.5]{figures/addToExperiment.eps}
  \end{center}
  \caption{Peptides can be added to a pre-existing experiment, or a new experiment can be created, from the \textit{Add to experiment} dialog window.}
  \label{fig:addToExperiment}
\end{wrapfigure}

Peptides can be added to an experiment by selecting the peptide(s) one wants to add to the experiment from a list of peptides and clicking the \textit{Add to experiment} button. Adding peptides to an experiment in this fashion can be done either from the list of peptides in an order, or from the list of peptides that a search in the database returns, utilizing the search field as described in Section~\ref{sec:peptideSearch}. Clicking the \textit{Add to experiment} button will bring up the dialog window shown in Figure~\ref{fig:addToExperiment}. An experiment to add the peptides to can be selected from the drop-down menu. For simplicity, a new experiment to add the selected peptides to can be created from within this dialog window if one does not wish to add the peptides to one of the pre-existing experiments. If the user creates a new experiment, it will be automatically added to the list and selected.

\section{Peptide search in HP LIMS}
\label{sec:peptideSearch}

Peptides stored in the database can be viewed from the order or the experiment(s) a peptide belongs to. If one is looking for a particular peptide or a group of peptides belonging to a particular protein it is possible to perform a search in the database by using the search field located in the top right corner of HP LIMS' user interface.

Figure~\ref{fig:searchView} shows part of the results returned when performing a search for peptides belonging to Secretogranin-3. A search was performed using Secretogranin-3's UniProt accession number, \textit{Q8WXD2}. Eleven peptides belonging to this protein were found in the database, two of which belonged to the order named ``Master Order'' while the rest belonged to ``Order 126''. One of these orders is completed and thus the sales order code of ``Master Order'', and the plate position of the peptides belonging to this order, are displayed in the search results to enable quick localization of the peptides in question. Clicking on either an order name or a UniProt accession number in the list will open the individual order or the protein's UniProt page, respectively.

\begin{figure}[htb]
\centering
\includegraphics[width=\textwidth]{figures/searchView.eps}
\caption{By utilizing the search field in the top right corner, the user can look for peptides stored in the database. The \textit{Search results} tab displays a list of all the peptides found to match the query string.}
\label{fig:searchView}
\end{figure}

Currently, peptides can be looked up in the database by using either of three different query types. All queries may correlate to either the entire field of a peptide or a smaller part of that field.

\begin{itemize}
	\item \textit{Sequence}: A search for a peptide sequence returns all peptides that contain the query sequence. 
	\item \textit{UniProt accession number}: All peptides that are set to belong to the query accession number are returned by a search for a UniProt accession number.
	\item \textit{Name}: Peptides can also be looked up based on its assigned name. This means that, e.g., protein name, protein short name (from UniProt), or species can be valid search criteria, as peptide names are generated from this information (see Section~\ref{subsec:blastProcedure}).
\end{itemize}

A search for peptides with sequence \texttt{QTDK} may return peptides with sequences such as \texttt{FLPQTDK} or \texttt{QTDKPTR}, while a search for \texttt{AFLPQTDK} will not return either of these two peptides.

\section{Individual peptide information}

Information about individual peptides can be accessed by double-clicking on a peptide from any list displaying peptide information. Such lists are currently found in orders, experiments and search results. Peptide information is opened and displayed to the user in a new window, the \textit{Peptide information} window displayed in Figure~\ref{fig:peptideInformation}.

\begin{figure}[htb]
\centering
\includegraphics[width=\textwidth]{figures/peptideInformation.eps}
\caption{\textit{Peptide information} window.}
\label{fig:peptideInformation}
\end{figure}

This window displays the peptide's sequence and the length of the sequence along with information about which protein the peptide belongs to. If it is revealed by BLAST search that the peptide maps to more than one protein one has to select which protein the peptide belongs to from the list of available proteins. Known modifications for the peptide is listed below the protein(s) the peptide maps to. If the BLAST search reveals that this peptide could belong to two or more proteins, the list of modifications will change depending on which protein is selected.

Figure~\ref{fig:peptideInformation} shows information about a peptide with sequence \texttt{LPLQDVYK}. The sequence consists of eight amino acids, and the BLAST search has revealed a relationship between this peptide and three proteins in UniProt. Upon closer inspection one can see that these three UniProt entries are clearly related. This can be seen from both the proteins' names, their shortnames and the start and end positions of the peptide within the proteins' sequences. Two of the proteins, Putative elongation factor 1-alpha-like 3 and Elongation factor 1-alpha 1, have a known modification in position 255, where a modified residue as been known to occur. The peptide in question starts at position 248 and ends at position 255 in these sequences, and thus the modifications pertain to this peptide.

After selecting which protein this peptide belongs to, the changes have to be saved by pressing the \textit{Save} button in order to take effect. The list of peptides from which the window was opened will then be updated with the new information about the peptide.

\section{Settings}
\label{sec:settings}

There are currently few settings that can be modified through the user interface of HP LIMS. Some additional settings to add are discussed in Section~\ref{sec:futureWork}.

\subsection{User administration}

Administration of user accounts is performed in the user interface. Regular users are allowed to administer their own user accounts, and are able to change their full name, email address and password. A user can only change his or her password if they also provide their current password. If the current password has been lost or forgotten, users have to contact an administrator to change their password. Regular users are not allowed to change their username. 

Administrators are allowed to change the user accounts of all users, including full name, e-mail address, username, and password. Passwords for all users can be changed by an administrator regardless of whether or not the user's current password has been provided. Only administrators are allowed to create new user accounts or delete existing accounts.

\begin{figure}[htb]
\centering
\includegraphics[width=\textwidth]{figures/userAdmin.eps}
\caption{From the \textit{Administer users} view in the \textit{Settings} tab administrators can edit user accounts. Here, users can be created, edited or deleted. A table showing all registered users is shown. The form on the right is used to create new users or edit existing users. Users without administrator privileges are not allowed to see the list of all users, but are provided with a similar form to edit their own user account.}
\label{fig:userAdmin}
\end{figure}
